Initiate MCP OAuth Flow

Used to initiate OAuth 2.1 Authorization Code flow for an MCP (Model Context Protocol) server. This endpoint returns an authorization URL that users should visit to grant permissions. After granting permissions, users will be redirected to the configured redirect_uri with an authorization code.

API Endpoint

Property	Value
Request Method	POST
Request URL	https://api.seliseblocks.com/tools/{tool_id}/initiate-oauth

Prerequisites

Before using this endpoint, ensure the following requirements are met:

• MCP server must be configured with OAuth2 auth_config
• Grant type must be set to AUTHORIZATION_CODE
• redirect_uri must be properly configured in the OAuth2 settings

Request

Request Example

curl -X POST 'https://api.seliseblocks.com/tools/{tool_id}/initiate-oauth?project_key=YOUR_PROJECT_KEY' \
  -H 'accept: application/json'

Path Parameters

Field	Type	Required	Description
tool_id	string	Yes	The unique identifier of the MCP server tool.

Query Parameters

Field	Type	Required	Description
project_key	string	No	The project key for your project.

Request Headers

Field	Type	Required	Description
accept	string	Yes	Accepted response format. Use application/json

note

OAuth Flow Requirements

• This endpoint requires no request body
• The MCP server must have OAuth2 authentication configured with authorization code grant type
• PKCE (Proof Key for Code Exchange) will be automatically applied if configured
• The authorization URL is valid for a limited time (typically 10-15 minutes)
• State parameter is automatically generated for CSRF protection

tip

OAuth Authorization Flow Steps:

1. Call this endpoint to get the authorization URL
2. Redirect the user to the authorization URL in their browser
3. User grants permissions on the OAuth provider's page
4. OAuth provider redirects back to your redirect_uri with an authorization code
5. Exchange the authorization code for access tokens using the callback endpoint
6. MCP server is now authenticated and ready to use

The system will:

• Generate a secure state parameter for CSRF protection
• Create PKCE code challenge if PKCE is enabled
• Build the authorization URL with all required parameters
• Store the OAuth flow state for verification during callback
• Return the authorization URL for user redirection

Response

Success Response (200 OK)

Returns an object containing the authorization URL and flow details.

{
  "authorization_url": "https://oauth.example.com/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&state=random_state_value&code_challenge=challenge_value&code_challenge_method=S256&scope=read+write",
  "tool_id": "mcp_server_123",
  "message": "Please visit the authorization URL to grant permissions"
}

Response Fields

Field	Type	Description
authorization_url	string	The complete OAuth authorization URL for user redirect.
tool_id	string	The identifier of the MCP server tool.
message	string	Instructions for completing the OAuth flow.

note

Authorization URL Structure The authorization URL includes the following parameters:

• client_id: Your OAuth client identifier
• redirect_uri: Where the user will be redirected after authorization
• response_type: Set to "code" for authorization code flow
• state: Random value for CSRF protection
• scope: Requested OAuth scopes
• code_challenge: PKCE challenge (if PKCE is enabled)
• code_challenge_method: PKCE method (typically "S256")

Error Response (422 Unprocessable Entity)

Returns validation error details when the request parameters are invalid.

{
  "detail": [
    {
      "loc": [
        "path",
        "tool_id"
      ],
      "msg": "MCP server not configured for OAuth authorization code flow",
      "type": "value_error.oauth"
    }
  ]
}

Error Response Fields

Field	Type	Description
detail	array	Array of validation error objects.
loc	array	Location of the error in the request (e.g., path, query).
msg	string	Human-readable error message.
type	string	Error type identifier.

Error Codes

Status Code	Description	Response Type
200	Successful Response	Success
400	Bad Request - OAuth not configured correctly	Bad Request
404	Not Found - MCP server tool does not exist	Not Found
422	Validation Error - Invalid request parameters or OAuth configuration	Unprocessable Entity